home *** CD-ROM | disk | FTP | other *** search
/ Logiciels PC Special 3 / Logiciel PC - Hors-Serie 3.iso / Logs / micros / ql / outils / qlayt090 / qlayt.man < prev   
Text File  |  1999-01-30  |  10KB  |  258 lines
  1.  
  2.         QLAYT    QL emulator tools for DOS/Linux
  3.  
  4.  
  5. Version 0.90, 19990130
  6.  
  7. 1. Copyrights
  8.  
  9. This program is freeware. You may do with it whatever you want for personal use.
  10. Copyright Jan Venema.
  11.  
  12. Permission is granted to redistribute this program free of charge, provided it
  13. is distributed in the full archive with unmodified contents. No profit beyond
  14. the price of the media on which it is distributed is made.
  15.  
  16. There are no warranties of any kind for this program. If you use this program,
  17. you do so at your own risk. The author is not responsible for any damages
  18. that might result from using this program.
  19.  
  20.  
  21. 2. Overview
  22.  
  23. QLAYT provides a set of tools and general support functions for the QL
  24. emulator QLAY. The tools are needed because the QL and it's operating
  25. system QDOS have some pecularities that do not match well with most
  26. other Operating Systems. Most obvious difference is that QDOS files consist
  27. of two parts: a header block and the actual data file. To allow transparent
  28. access from the emulator program to the native file system it's needed
  29. that the file header is stored separately.
  30.  
  31. The QLAYT program takes care of inserting or extracting files into/from
  32. a directory file. It knows about datasize fields. And will import and
  33. export files from other QDOS compatible systems and QLAY's MDV file format.
  34.  
  35. QLAY uses a directory file -called qlay.dir- to store the headers of all
  36. files that it needs to access during emulation. The stored headers are
  37. similar to the QDOS header: for each file a 64 byte data field is used.
  38. The header block maintains the file length (header inclusive), the
  39. file name (up 36 character), the modification date and an optional data
  40. size field.
  41.  
  42. Before QLAY can access any files, their headers must be constructed in the
  43. file 'qlay.dir'. Any file in the native directory stored in 'qlay.dir' can be
  44. accessed during emulation as on a real QL. All other files are simply
  45. invisible for QLAY.
  46.  
  47. A tricky part is setting the correct datasizes for an executable QDOS
  48. program. Some executable files have the datasize stored in a XTcc field
  49. in the file itself. QLAYT can use those.
  50. Another way to get the value is from a InfoZIP archive file that was
  51. archived with a QDOS compatible ZIP program. QLAYT can read those datasizes.
  52. Of course, you can also unzip a file in the QLAY emulator with the
  53. QDOS InfoZIP 'unzip'. (It has a proper XTcc field :-)
  54. If all else fails, simply try it with a reasonably large number...
  55.  
  56. NOTE: QLAY does not support sub-directories of any kind (yet).
  57.  
  58. QLAY uses a 'MDV' file format to emulate the Microdrive cartridges. Each
  59. cartridge is store as in a single file. It has a format very much like the
  60. magnetic bit pattern found on the end-less tape inside the QL cartridges.
  61. The file is not end-less (!), but wraps around after 174930 bytes exactly.
  62. QLAYT has options to import and export files from a 'MDV' file.
  63. The 4 original PSION cartridges are already converted and available
  64. on my website.
  65.  
  66. NOTE: there is no option in QLAYT to get an **exact** copy of a QL
  67. cartridge (yet).
  68.  
  69. Since there are several QL compatible systems and various file storage
  70. formats QLAYT has also some functions to extract files and header
  71. information. It can extract files from QLAY's own MDV file format,
  72. from QXL disk images (untested) and can read file headers from QDOS files
  73. compressed in an InfoZip archive.
  74.  
  75.  
  76. 3. Invocation, options and use
  77.  
  78. QLAYT exists in DOS and Linux versions. The DOS file is 'qlayt.exe'; the
  79. Linux version 'qlayt'. Both version have the exact same options and use.
  80. Invoked without options QLAYT will show help text.
  81. The default directory file for directory operations is 'qlay.dir'.
  82.  
  83. 3.1 Command line options
  84.  
  85. -l    List the contents of the directory file. The output can be
  86.     redirected to a file for later use. See 'use' section below.
  87.  
  88. -c file Create a new QLAY directory file. All files listed in 'file'
  89.     are included.
  90.  
  91. -a file Append to an existing QLAY directory file. All files listed in
  92.     'file' are appended.
  93.  
  94. -i file    Include a single DOS/Linux 'file' in the QLAY directory file.
  95.  
  96. -r file Remove a single DOS/Linux 'file' from the QLAY directory file. The
  97.     file itself is not removed.
  98.  
  99. -u file    Update the header information for 'file'. This action is needed
  100.     when a file, listed in the QLAY directoy file, is modified by a
  101.     DOS/Linux editor or so. The file length and other header data may
  102.     have changed.
  103.  
  104. -d size    To be used together with option -i. Specifies the datasize for
  105.     executable files. Specify size as decimal number.
  106.  
  107. -X    To be used together with option -i. QLAYT will try to find a XTcc
  108.     datasize field in the file. This is often available in modern
  109.     compiled QDOS programs.
  110.  
  111. -x file Show the XTcc field of 'file'. The datasize, if found, will be
  112.     shown. The QLAY directory file will not be updated.
  113.  
  114. -z file Show the QDOS headers in a ZIP 'file'. QDOS files that were archived
  115.     in a ZIP file with InfoZip and QDOS extensions will store the
  116.     header internally. The headers, if found, will be shown. The output
  117.     can be redirected to a file for later use. See 'use' section below.
  118.     The QLAY directory file will not be updated.
  119.  
  120. -q file    Use 'file' as the QLAY directory file; this in stead of the default
  121.     directory file 'qlay.dir'.
  122.  
  123. -W file    Write all files contained in an MDV 'file' to the current directory,
  124.     and store the header information in file 'qlay.dir'.
  125.     The default 'qlay.dir' can be changed with option -q.
  126.     QDOS has different rules for filenames and their length than DOS or
  127.     Linux. For this reason some files may be renamed with a legal
  128.     DOS/Linux file name.
  129.  
  130. -C file Create an MDV image file from the files listed in 'file'. The
  131.         MDV image file will be stored as 'qlay.mdv'. This default can be
  132.     changed with option 'o'.
  133.  
  134. -R hex  Insert a random sector number on MDV file. Use together with -C.
  135.     hex must be a hexadecimal value 0 <= hex <= ffff.
  136.  
  137. -o file Use 'file' as the MDV image file; this in stead of the default
  138.     'qlay.dir'.
  139.  
  140. -E file    Extract all files contained in an QXL disk image 'file' to the
  141.     current directory, and store the header information in file
  142.     'qlay.dir'.
  143.     The default 'qlay.dir' can be changed with option -q.
  144.     QDOS has different rules for filenames and their length than DOS
  145.     or Linux. For this reason some files may be renamed with a legal
  146.     DOS/Linux file name. Untested: need feedback!
  147.  
  148. -m file1 file2 Convert 'file1' in the native file system (DOS or Linux) to
  149.     a QDOS 'file2'. Specify optional datasize with:
  150.     -d size -m file1 file2
  151.     Specify size as decimal number.
  152.     Us this to convert a file what needs to be sent to a real QL.
  153.  
  154. -n file1 file2 Convert QDOS 'file1' to the native file system (DOS or Linux)
  155.     'file2'. If 'file1' contains a datasize, that will be printed in
  156.     decimal format.
  157.     Use this to convert a file that was received from a real QL.
  158.  
  159. Additional notes:
  160.  
  161. For all options where files are to be included in the QLAY directory file
  162. (-c, -a, -i, and -u) those files must exist in the current DOS/Linux
  163. directory, otherwise they will be skipped.
  164.  
  165. QLAYT will check for duplicate file names in the QLAY directory file.
  166.  
  167. QLAYT will not overwrite an existing QLAY directory file with option -c.
  168.  
  169. QLAYT must not be executed while QLAY is active! If changes need to be
  170. made to the QLAY directory file, and those changes can not be done from
  171. within QLAY, it is necessary to quit QLAY. After that the change can be
  172. made with QLAYT.
  173.  
  174.  
  175. 3.2 Usage of QLAYT
  176.  
  177. Assume there is no QLAY directory file. To get started, create a list
  178. of files that needs to be accessed from QLAY.
  179.  
  180. The list can be generated with the following command:
  181. DOS    dir/b > qlay.lst
  182. Linux    ls > qlay.lst
  183.  
  184. Edit the file qlay.lst as needed.
  185.  
  186.     qlayt -c qlay.lst    creates a 'qlay.dir' file
  187.  
  188. Check the contents with:
  189.  
  190.     qlayt -l
  191.  
  192. The files listed are now available for access by the QLAY emulator.
  193.  
  194. Suppose you have a single file 'abc.txt' to be added to the list. Use:
  195.  
  196.     qlayt -i abc.txt
  197.  
  198. If file 'clock_exe' is a QDOS executable you might try:
  199.  
  200.     qlayt -i clock_exe -X
  201.  
  202. Or if that fails, and you happen to know the correct datasize (e.g. 1024):
  203.  
  204.     qlayt -i clock_exe -d 1024
  205.  
  206. It also possible to use the information from 'qlay.dir':
  207. Suppose a InfoZIP file was decompressed by the QLAY emulator. Then
  208. all file headers are stored in 'qlay.dir'. That information can be
  209. stored in ASCII format with:
  210.  
  211.     qlayt -l > qlay.lst
  212.  
  213. The 'qlay.lst' file can than later be used to generate another directory file:
  214.  
  215.     qlayt -a qlay.lst
  216. or
  217.     qlayt -c qlay.lst
  218.  
  219. To extract all files from a QXL disk image file called 'qxlfile':
  220. Method 1:
  221.     qlayt -E qxlfile > qlay.lst
  222.     qlayt -c qlay.lst
  223.  
  224. Method 2:
  225.     qlayt -E qxlfile
  226.     rename qxl.dir qlay.dir
  227.  
  228. Method 3:
  229.     qlayt -E qxlfile -q qlay.dir
  230.  
  231.  
  232. 4. History
  233.  
  234. 090c    added random sector number for MDV; option -R
  235. 083a    added QDOS <-> DOS file conversion (chop/generate 64 byte header)
  236.     added Linux version
  237. 082f    first release
  238.  
  239. The QLAYT program is a combination of the separate programs that came with
  240. earlier distributions of QLAY: fil2mdv, dos2qdos, qdos2dos and fil2win.
  241.  
  242. Main difference is that all options use the same file format. QLAYT never
  243. expects the QDOS header to be part of a file when operating under MS-DOS
  244. or Linux.
  245. All file header information is kept the directory file 'qlay.dir'.
  246.  
  247. 5. Known bugs, non-features
  248. - QLAYT was developed under Win95 and may be less usable on a '8.3' file
  249.   system like Win31 or OS/2 in DOS box. Expect a solution later.
  250. - QLAYT does not handle improper filename characters or spaces in filename.
  251.  
  252. 6. Info and updates
  253.  
  254. http://www.inter.nl.net/hcc/A.Jaw.Venema
  255. A.Jaw.Venema@net.hcc.nl
  256.  
  257. Jan Venema
  258.